Add 0082 structured-output failure event surface#229
Merged
chris-colinsky merged 1 commit intoJul 22, 2026
Conversation
PR A of proposal 0082 (the event + error surface; the OTel/Langfuse rendering and the token metric follow in later PRs). A structured_output_invalid failure is a completion whose final validation gate failed, so the wire response is intact. LlmFailedEvent now carries the response-side surface for that one category (null for every other): output_content (payload-gated), finish_reason (the truncation-vs-malformed triage signal), usage, response_id, and response_model. StructuredOutputInvalid additionally exposes finish_reason and usage so a caller's exception handler can make a truncation-aware retry decision. The response-side data lives in the parsed response, not in the helper that raises the error, so the OpenAI provider attaches it to the error at the parse/validate call site and the failed-event builder reads it off the enriched error. error_message carries the failing-field locator (the failure description), not just the terse category summary. Un-defers observability fixtures 120/121/122 (driven via a new calls_llm.response_schema harness lever) and llm-provider fixtures 022/023 (whose carries block now asserts finish_reason + usage; the carries reader gained subset matching for a mapping-valued field like usage). conformance.toml marks 0082 partial.
There was a problem hiding this comment.
Pull request overview
Implements proposal 0082’s structured-output failure diagnostics surface in the Python reference implementation by enriching structured_output_invalid failures with response-side context, and wiring conformance/unit coverage to validate the new behavior.
Changes:
- Extend
LlmFailedEventto optionally carry response-side fields (output_content,finish_reason,usage,response_id,response_model) only forstructured_output_invalid. - Extend
StructuredOutputInvalidto exposefinish_reason+usage(and carry response identity for event building), and enrich the error at the OpenAI parse/validate call site. - Update unit + conformance harness/tests/docs/config to assert the new surfaces and un-defer the relevant runtime-driven fixtures.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| tests/unit/test_structured_output.py | Asserts StructuredOutputInvalid carries response-side context (finish_reason/usage/identity) on validation failures. |
| tests/unit/test_llm_provider.py | Adds a structured-output failure event test and updates failure-event error_message expectations. |
| tests/conformance/test_observability.py | Wires calls_llm.response_schema through the typed-event harness to drive 0082 structured-output failure fixtures at runtime. |
| tests/conformance/test_llm_provider.py | Removes deferrals for 0082 llm-provider fixtures now covered by the enriched error surface. |
| tests/conformance/test_fixture_parsing.py | Keeps 120–122 parse-deferred but updates rationale now that runtime behavior is implemented. |
| tests/conformance/harness/wire.py | Adds subset-matching support for mapping-valued carries fields (notably usage). |
| src/openarmature/observability/langfuse/observer.py | Updates metadata-rendering commentary to reflect new failed-event response-side fields (rendering still deferred). |
| src/openarmature/llm/providers/openai.py | Enriches StructuredOutputInvalid with response-side context at parse/validate and maps those fields into LlmFailedEvent. |
| src/openarmature/llm/errors.py | Extends StructuredOutputInvalid with finish_reason, usage, response_id, response_model and documents enrichment semantics. |
| src/openarmature/graph/events.py | Extends LlmFailedEvent with response-side fields populated only for structured_output_invalid. |
| docs/concepts/observability.md | Updates docs to describe the structured-output-only response-side surface on LlmFailedEvent. |
| conformance.toml | Marks proposal 0082 as partial for 0.17.0 (event + error surface implemented; rendering deferred). |
| CHANGELOG.md | Adds a 0.17.0 entry describing the new structured-output failure diagnostics surface. |
chris-colinsky
deleted the
feature/0082-structured-output-failure-diagnostics
branch
July 22, 2026 23:25
This was referenced Jul 23, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Phase A Wave 2 of the v0.17.0 cycle. PR A of a 3-PR split for proposal 0082 (structured-output failure diagnostics, graph-engine §6 + llm-provider §7, spec v0.77.0): this PR lands the event + error surface; the OTel error-span rendering, the Langfuse failed-Generation rendering, and the §11 token-usage-on-failure metric follow in PRs B and C.
Why
A
structured_output_invalidfailure is a completion whose final validation gate failed, so the wire response is intact. Today the failure event carries none of that response, so an observer or a retry classifier cannot tell a truncation (finish_reason: "length", the model hitmax_tokens, may succeed on retry) from a clean-finish schema violation (finish_reason: "stop", usually fails the same way). Failed structured calls also render as zero tokens in Langfuse, dropping out of cost accounting.What
LlmFailedEventgains the response-side surface for that one category (Nonefor every other):output_content(payload-gated),finish_reason,usage,response_id,response_model. MirrorsLlmCompletionEventlessoutput_tool_calls.StructuredOutputInvalidadditionally exposesfinish_reason+usage, so a caller's exception handler can make a truncation-aware retry decision.error_messagecarries the failing-field locator plus the summary, not just the terse category label.Conformance / tests
calls_llm.response_schemaharness lever; and llm-provider 022/023, whosecarriesblock now assertsfinish_reason+usage(thecarriesreader gained subset matching for a mapping-valued field likeusage).error_messagelocator, and assert the fields areNonefor a non-structured failure.typed_event_collectorshape the strict cross-cap parser doesn't model as 069-073); only runtime driving is un-deferred.conformance.tomlmarks 0082partial; the concept doc's now-false "carries minus the response-side fields" claim is corrected.Reviewed with a multi-agent adversarial pass (0 blockers); its two findings (the
error_messagelocator and stale Langfuse comments) are folded in. Full suite green.